Flash Image Scroller - 1.6
Overview
The Flash image scroller is a simple, free (GNU-licenced), highly configurable Flash
script that you can add to your webpages to provide an intuitive "window" to scroll
through a series of thumbnail images. Currently it only allows for horizontal scrolling. It
is compatible with any server side language like PHP, ASP, JSP, ColdFusion etc.
|
|
- JavaScript must be enabled
- You must have Flash installed
Included in the download package is Geoff Stearns' excellent SWFObject (formerly FlashObject). This is a Flash detection and embed script, which does all the nitty gritty of determining whether or not a person's browser is capable of running the script. SWFObject greatly simplifies your job of adding the image scroller to your website in a cross-browser friendly manner. It's available for download and use under the MIT license. Also, the Flash / JavaScript Integration Kit written by Christian Cantrell and Mike Chambers from Adobe. This script allows us to send information from Flash to JavaScript.
A few examples
1. A strip of thumbnails of some galaxies. Scroll speed is set to a maximum and the padding between images is reduced to a mere 3 pixels. No links have been defined for each thumbnail, so clicking on the thumbnails does nothing. Smooth Loading has been enabled, and the fade-in time for the thumbnails has been lowered to 2 (out of 20), so we get a nice left-to-right fade in effect. Also note the directional arrows have a custom colour defined (blue).
Requirements:
- JavaScript must be enabled
- You must have Flash installed
2. Some rather beautiful paintings by Pieter Bruegel. Note that the thumbnails are vertically aligned, clicking on the thumbnails opens the full image in a separate window and the scroller colours have been set to match this site. Auto scrolling is enabled, set to go off 2 seconds after loading. (Auto scrolling is de-activated when the user moves their mouse over the scroller - it stops at the next thumbnail).
- JavaScript must be enabled
- You must have Flash installed
2. A few shots of my girlfriend's pets (she has a lot more). Note the alternate thumbnail sizes, the addition of a caption, the slower scrolling speed, that the thumbnails are horizontally, but not vertically aligned, and that the images are randomized on page load.
- JavaScript must be enabled
- You must have Flash installed
Configuration options
Here's an example of an image scroller definition, containing all supported configuration options. As you can see, the configuration is done in the javascript, embedded in your page. The required fields are marked off in their own section. Each setting is explained in the table below - note, these settings are case sensitive!
| Option | Definition | ||||||||||||||||
Required Fields |
|||||||||||||||||
| sourceFile |
This is the source file containing the content to display in the image scroller.
The content to be displayed can be in either a query string format, or an XML file.
1. Query String formatted file
(where X is a number beginning with 1). Each value must be separated by an ampersand (&) character as in a query string, e.g. &thumbURL1=/path/to/image1.jpg&title1=My Caption&thumbURL2=/path/to/image2.jpg&title2=My Second Caption& The downloadable zipfile contains a couple of examples of how this file can be built and how it is structured. 2. XML file
Nodes:
The downloadable zipfile contains a blank XML file with the appropriate nodes. |
||||||||||||||||
| fileType | Either "XML" or "text" to indicate what format the source file is in. This field isn't strictly required, since it will default to "text", but it never hurts to include it. | ||||||||||||||||
| stageWidth | The width of the scroller, in pixels. | ||||||||||||||||
| stageHeight | The height of the scroller, in pixels. | ||||||||||||||||
| thumbSize | The maximum size of the thumbnails to be displayed. This should be set to the greatest width or height of the set of thumbnails. Ideally, thumbnails should be of a consistent height / width for best appearance. | ||||||||||||||||
Optional Fields |
|||||||||||||||||
| randomize | If this setting is included, it will automatically randomize the contents of the scroller. Note: if you don't want it to be randomize, omit the option altogether (don't just set it to "no"). | ||||||||||||||||
| maxNumItems | This lets you control the limit the number of items that appear in the scroller. If, for example, your XML feed contains 100 items, but only wanted to display 50, you could set this value to 50: it will then only show the first 50 items. Or, if used in conjunction with the "randomize" option, it will show a random subset of 50 items taken from the total set of 100. | ||||||||||||||||
| scrollSpeed | An integer value of 1-20, determining the speed of the scroller (1 = slowest). Remember that scrolling speeds will be different depending on the person's computer speed. The default speed is 10. | ||||||||||||||||
| bgColor | The background colour of the scroller in hex (e.g. 336699). Be sure to omit the "#" sign and only include the colour code. The default background colour is white (ffffff). | ||||||||||||||||
| navColor | The background colour of the nav bars in hex (e.g. ffffee). As with the bgColor, be sure to omit the "#" sign and only include the six characters. When there are no more items to scroll in one particular direction, the appropriate nav bar (left or right) will be faded out to 30% of it's original colour, to indicate to the user that he/she can't scroll any more. The default background colour is dark grey (7c7c7c). | ||||||||||||||||
| arrowColor | The colour of the nav bar arrows in hex (e.g. ffffee). As with the other colour settings, be sure to omit the "#" sign and only include the six characters. The default background colour is white (ffffff). | ||||||||||||||||
| thumbAlign | This determines how the thumbnail is to be aligned within it's square. The options are "vertical", "horizontal", "both" or "none". The default position is none (i.e. top left). | ||||||||||||||||
| captionSize | This is the text size of the caption in pt. The default is 10pt. | ||||||||||||||||
| captionColor | This is the text colour of the caption. The default is black. | ||||||||||||||||
| captionAlign | This determines the alignment of the caption text. There are three options: "left", "center" and "right". The default is center. | ||||||||||||||||
| thumbPadding | This setting lets you control the amount of padding (in pixels) around a thumbnail. It applies to all four directions: left, right, above and below. This provides you with a means to evenly distribute your thumbnails along the width of the image scroller without having some unsightly leftover space at the end. The default padding is 10 pixels. | ||||||||||||||||
| thumbPaddingTop | This and the following option provide you with a little more control over the spacing in the image scroller - specifically, the space above the thumbnail. Note: this is in conjunction with thumbPadding - it does not override the thumbPadding setting. So, if you wanted a larger width between thumbnails, but a smaller height, you could set a negative value for thumbPaddingTop. This is defaulted to 0 pixels. | ||||||||||||||||
| thumbPaddingBottom | Just like thumbPaddingTop, except for the bottom of the thumbnail. Handy for adding a little padding between a thumbnail and its caption. This is defaulted to 0 pixels. | ||||||||||||||||
| thumbBackgroundColor | The color of the background squares that appear behind each thumbnail. This is handy if your images are not all of a fixed size; it nicely frames your thumbnails. The default colour is grey, #cccccc. | ||||||||||||||||
| thumbBackgroundOpacity | The opacity of the background coloured squares behind each thumbnail. This allows values of 0-100, where 0 is completely faded out, and 100 is full colour. The default value is 50. | ||||||||||||||||
| jsClickHandler | This option lets you specify the name of the javascript function that will be called when a user clicks a thumbnail. If this value is not specified, the default function name is image_scroller_clicked. If you are not using the javascript functionality, just ignore this configuration option. You can learn more about how to pass thumbnail information to javascript here. | ||||||||||||||||
| autoScroll | This option, if set to yes, makes the scroller automatically begin scrolling on page load. By default, auto-scrolling is deactivated. Auto-scrolling will continue until the user rolls their mouse over the scroller or it reaches the end of the list of thumbnails. | ||||||||||||||||
| autoScrollSpeed | This option lets you determine the speed of the auto-scrolling. The valid values are 1-20, but note that these speed values are 1/4th as fast as the scrollSpeed value, since auto-scrolling would generally be a lot slower than the scroll speed - this allows you to fine tune it a little better. The default value is 4. | ||||||||||||||||
| autoScrollPause | This lets you determine the wait time after the scroller has loaded and when it begins auto scrolling. This value is in milliseconds (1sec = 1000ms). The default value is 1000. | ||||||||||||||||
| smoothLoad | This option is purely aesthetic: if set to yes, instead of just loading the first page of thumbnails as soon as they load (in any order), it loads them sequentially from left to right. When used in conjunction with the two following options, initFadeInSpeed and initFadeInItemPause, it can create a very nice effect indeed. See the galaxy thumbnails on the example page for an illustration. This feature is de-activated by default. | ||||||||||||||||
| initFadeInSpeed | This option lets you control the speed at which the first page thumbnails fade in, when using the smoothLoad option above. The valid options are 1-20 (1 == slowest, 20 == fastest). The default value is 5. | ||||||||||||||||
| initFadeInItemPause | This lets you determine the pause between each item fading in. If you have a lot of thumbnails appearing per page, you'll probably want a small value. The default value is 400 milliseconds. | ||||||||||||||||
Installation
Getting the image scroller installed and operational is a fairly simple process. It shouldn't pose any problems for web developers but it may be a little daunting for non-technical types. So to help out, here's some step by by step instructions on how to get it up and running.
Note, you'll need to first download the zipfile to your computer which contains all the relevant files.
1. Import swfobject.js and scroller_x.swf
From the downloadable zipfile, extract the swfobject.js and scroller_x.wsf files and upload them to the same folder as the webpage to which you're adding the image scroller. Note: you can actually place it wherever you want, but the sake of simplicity we're going to assume it's in the same folder.
2. Set up your scroller
In between the <head> ... </head> tags of your page, import the javascript library:
<script type="text/javascript" src="swfobject.js"></script>
Next, add the following chunk of HTML and JavaScript into the place in your page where you would like the image scroller to appear.
<div id="scroller1" style="width:600px; height: 66px;"> Your browser is not able to run this Flash script.<br /> <br /> Requirements: <br /> - JavaScript must be enabled<br /> - You must have Flash installed<br />
<script type="text/javascript">
var so3 = new SWFObject("scroller_x.swf", "scroller1", "100%", "66", "6");
so3.addVariable("sourceFile", "my_thumb_info.txt");
so3.addVariable("fileType", "text");
so3.addVariable("scrollSpeed", "10");
so3.addVariable("stageWidth", "600");
so3.addVariable("stageHeight", "66");
so3.addVariable("thumbSize", "60");
so3.addVariable("bgColor", "666666");
so3.addVariable("navColor", "333333");
so3.write("scroller1");
</script> </div>
Now tweak that code to fit for whatever settings you want: your thumbnail size, the scroller width and height and the background and nav bar colours. It may take a little back-and-forth to get the scroller looking the way you want it. Take a look here for a full list of the available configuration options.
Here's how this code works. When the page is loaded, if the SWFObject code determines that the browser can handle it, it replaces the div content marked with id="scroller1" with the flash program specified in the first parameter of the SWFObject constructor call. The third parameter is the width (always leave at 100% since you've specified the width in the overall div tag); the fourth parameter is the height. This must be included since setting it to 100% may confuse IE. The final parameter is the version of Flash required to run the script: in this case, version 6.
4. Create your thumbnail source file
This will be the trickiest part for non-technical users. Basically, your job is to create a file that contains the information (thumbnails, captions and other) to funnel into the image scroller. This can be created in two different formats, depending on your preference: a query string file, or an XML file.
1. Query string file:
&thumbURL1=http://yoursite.com/path/to/th_img1.jpg&title1=My Caption 1&targetX=_blank&linkURL=http://yoursite.com/path/to/img1.jpg&
&thumbURL2=http://yoursite.com/path/to/th_img2.jpg&title2=My Caption 2&targetX=_blank&linkURL=http://yoursite.com/path/to/img2.jpg&
&thumbURL3=http://yoursite.com/path/to/th_img3.jpg&title3=My Caption 3&targetX=_blank&linkURL=http://yoursite.com/path/to/img3.jpg&
&thumbURL4=http://yoursite.com/path/to/th_img4.jpg&title4=My Caption 4&targetX=_blank&linkURL=http://yoursite.com/path/to/img4.jpg&
&thumbURL5=http://yoursite.com/path/to/th_img5.jpg&title5=My Caption 5&targetX=_blank&linkURL=http://yoursite.com/path/to/img5.jpg&
The required sections are in red. The optional sections are in green. As you can see from a glance, only the thumbnail URL is required. The caption (titleX), target (e.g. _blank for a new window, the parent window or the name of a frame, etc.) and link URL (where to link to when the user clicks the thumbnail) are all optional.
Make sure you end every line with an & character.
2. XML file:
Your XML file should have the following structure:
The order of the item nodes are not important, and within the item nodes, only the thumbURL node is required.
When you have created your file, upload it to your folder on your server and call it my_thumb_info.txt or whatever you specified in the code in your page. Now refresh your page in your browser - if all went well you should see your populated image scroller!
How to fail gracefully
Bear in mind that there's a lot of users out there that don't have Flash or JavaScript installed/enabled. Without both of those, the script will be unable to function - so you need to plan for that eventuality. Luckily, Geoff Stearns' SWFObject script detects this very situation for us.
In the example above, you'll notice some text inside the div tag informing the user that their browser can't handle the script. That text only appears in that eventuality. So, you might want to consider replacing it with some static thumbnails - that way the worst case scenario will be that they will at least be able to see some images!
Pass thumbnail info to javascript
With version 1.5, you now have the option of passing the information about the thumbnail to javascript when the user clicks the thumbnail. For example, you could use it to keep track of which thumbnails a person clicks, or load the appropriate thumbnail into a page element via javascript code - whatever you need! See here for a simple example of how to load the image thumbnail to a page div tag.
A big thanks to Digital Nemexis for sponsoring this feature.
To pass the thumbnail information to javascript, you need to do three steps.
- Included in the downloadable zipfile is a javascript file called JavaScriptFlashGateway.js.
Include this file in the head of your page, like so:
<script type="text/javascript" src="JavaScriptFlashGateway.js"></script>
This file is part of the Flash / JavaScript Integration Kit written by Christian Cantrell and Mike Chambers from Adobe. It allows us to send information from Flash to JavaScript.
-
Next, write a separate function that handles the return value from the image scroller. Here's an example
which lists all the object properties available.
<script type="text/javascript"> // handles the information send from the image scroller. Information is sent via a single parameter, // of type Object. function image_scroller_clicked(info) { var index = info.index; var linkURL = info.linkURL; var thumbURL = info.thumbURL; var thumbWidth = info.thumbWidth; var thumbHeight = info.thumbHeight; alert(thumbURL); } </script>
The name of this function may be customized to whatever you wish, by setting the jsClickHandler configuration option. If you do not set this option with your own custom javascript function name, it will look for a function named image_scroller_clicked.
-
Lastly, you need to let the image scroller know to send the information via javascript. This is done
through by setting the "target" value to "javascript". For example, here's how it would work through
the query string formatted file:
&thumbURL1=http://yoursite.com/path/to/th_img1.jpg&title1=My Caption 1&target1=javascript&linkURL=http://yoursite.com/path/to/img1.jpg&
And here's how you would set it via XML:
&thumbURL2=http://yoursite.com/path/to/th_img2.jpg&title2=My Caption 2&target2=javascript&linkURL=http://yoursite.com/path/to/img2.jpg&
- <?xml version="1.0" encoding="UTF-8"?>
- <items>
- <item>
- <thumbURL>http://www.yoursite.com/yourthumb.jpg</thumbURL>
- <linkURL>http://www.google.com</linkURL>
- <caption>A link to google!</caption>
- <target>javascript</target>
- </item>
- </items>
And you're done! Now you can do whatever you want with the thumbnail information from with javascript. Just for your reference, here are all the object properties available in your return function.
| index | The position of the thumbnail within the image scroller (indexed from 0). |
| linkURL | The linkURL value specified for the thumbnail. |
| thumbURL | The thumbnail URL. |
| thumbWidth | The width of the thumbnail. |
| thumbHeight | The height of the thumbnail. |
Download file and contents
You can download the zipfile here. Here's a list of the contents.
- swfobject.js
- JavaScriptFlashGateway.js
- scroller_x.swf
- get_folder_images.php
- license.txt
- sample.xml
The get_folder_images.php file is a separate little script which may come in handy. It parses the contents of a image folder and generates the image information in a format understood by the image scroller. It's really just a single basic illustration for how you can automate the generation of the thumbnail source file. The sample.xml file contains the XML structure for the XML source file option.
If you would like a copy of the original .fla file, please send me an email detailing what you plan on doing with it. If you're planning on using this for commercial use, donations are always appreciated!
Getting Help / Feature Requests
I won't fib, I'm always very busy with other projects - but I'll try and help if and when I can. Just add your comments / questions to this post and your feature requests here. I'll respond to you there. Please note that sponsored features take the first priority. I'd love to hear from you if it's come in useful - and donations are always appreciated!
Thanks!
Donate!
If this tool has helped you in your work, a donation is always appreciated! Your donations goes a long way to supporting the script and lead to nice new features. Use the form below to donate by PayPal or credit card.
Sponsor a new Feature
Like to see a new feature added to the Flash Image Scroller? Then you might want to consider sponsoring it! Please contact me with a explanation of what feature(s) you would like to see added and I will provide you with a time and cost estimate.
Please be aware that generally I only work on features that can be incorporated into the main public build of the software. I give preferential treatment to features that can be used by everybody. This is open source! Embrace the philosophy! :-)
